Say that unbalanced initialization errors come from initialization - #4897

Draft — please ignore until reviewed by @ChrisRackauckas.

The problem

Reported by Michael Tiller: a Dyad model built for the JuliaCon workshop failed with

ERROR: ExtraVariablesSystemException: The system is unbalanced. There are 2 highest order derivative variables and 1 equations.
More variables than equations, here are the potential extra variable(s):
 inertia₊wˍt(t)
Note that the process of determining extra variables is a best-effort heuristic. The true extra variables are dependent on the model and may not be in this list.

The counting is correct and the fix is "supply one more equation", but nothing in the message says which system is unbalanced. The model's own equations are fine; it is the initialization system that is short an equation. The only indication of that is the stack trace. On top of that, inertia₊wˍt(t) is D(inertia₊w), a variable the user never wrote, and the message gives no hint of how to supply the missing equation.

Reproducer

Not Dyad-specific — plain MTK reproduces it, and shows the progression:

using ModelingToolkit
using ModelingToolkit: t_nounits as t, D_nounits as D

@parameters J = 1.0
@variables phi(t) w(t)
@mtkcompile sys = System([D(phi) ~ w, J * D(w) ~ 1.0 * t], t)

ODEProblem(sys, [], (0.0, 1.0); fully_determined = true)          # InvalidSystemException: structurally singular
ODEProblem(sys, [phi => 0.0], (0.0, 1.0); fully_determined = true) # ExtraVariablesSystemException, as above
ODEProblem(sys, [phi => 0.0, w => 0.0], (0.0, 1.0); fully_determined = true)  # builds

The change

InitializationProblem compiles the initialization system at exactly one place. That call is now wrapped so structural errors are rethrown with the missing context. The exception type is unchanged, so existing code (and the existing @test_throws in the suite) that catches ExtraVariablesSystemException / ExtraEquationsSystemException / InvalidSystemException still works — only the message changes.

The same case now reports:

ExtraVariablesSystemException: Initialization system is underdetermined.

This is an error in the initialization system, not in the equations being integrated. The
initialization system solves for the value of every unknown of the model, and of their
derivatives, at the initial time. It needs as many equations as there are such values to
solve for. Initial conditions and bindings given for the model become equations of this
system.

The system is unbalanced. There are 2 highest order derivative variables and 1 equations.
More variables than equations, here are the potential extra variable(s):
 inertia₊wˍt(t)

1 more equation is needed to determine the initial state.

Any of the following supplies one missing equation:

  * Give an initial value in the problem constructor, as in
    `ODEProblem(sys, [x => 1.0], tspan)`.
  * Give one in the model, via `initial_conditions` or `bindings`.
  * Add an equation relating initial values, via the `initialization_eqs` keyword argument
    of the system or of the problem constructor.

`guesses` are starting values for the initialization solve rather than constraints on it,
so adding a guess does not add an equation. To solve an underdetermined initialization in
a least squares sense instead, pass `fully_determined = false` to the problem constructor;
the guesses then decide which of the possible initial states is found.

See https://docs.sciml.ai/ModelingToolkit/stable/tutorials/initialization/ for more information.
Note that variables named with a `ˍt` suffix are derivatives at the initial time: `xˍt` is `D(x)`.

Note that the process of determining extra variables is a best-effort heuristic. The true extra variables are dependent on the model and may not be in this list.

Three variants are handled, each with its own remedy paragraph:

• ExtraVariablesSystemException → underdetermined
• ExtraEquationsSystemException → overdetermined
• InvalidSystemException (singular message only) → structurally singular, i.e. balanced but with a redundant condition

Notes on two choices:

• The deficit count ("1 more equation is needed") is obtained by recompiling the initialization system with the balance check off and taking nunknowns - neqs. This costs a second compile, but only on the path that is about to throw. Only the difference is reported, not the absolute counts: that compile simplifies further than the one that failed, so its raw counts do not line up with the ones structural analysis prints, and showing both pairs would be worse than showing one.
• InvalidSystemException is also thrown for things that have nothing to do with the balance of a system ("Illegal unknown: …", derivative on the RHS). Only messages that report structural singularity are rewritten; the rest pass through untouched.

ExtraVariablesSystemException and friends are defined both in ModelingToolkitBase and in StateSelection.jl, which ModelingToolkitBase does not depend on, so the two are matched by type name. The alternative is to thread a "this is an initialization system" flag from mtkcompile down into StateSelection.check_consistency and build the message at the source, which would also let it print D(w) instead of wˍt and drop the second compile. That is the better long-term shape but spans two repos; happy to do it that way instead if preferred.

Tests

Added to lib/ModelingToolkitBase/test/initializationsystem.jl, alongside the existing @test_throws cases that already cover both the under- and over-determined paths:

• the raised error still has the same type, its message names the initialization system, and the original structural message is retained
• a direct test of the message builder for all three variants, including that the deficit sentence is omitted when the counts are unknown or do not corroborate the reported imbalance

Not addressed here

Michael also noted that the AI assistant diagnosed this as "just specify an initial condition for phi" and claimed to have verified it without running the analysis. That is an agent-side issue, not a ModelingToolkit one.

🤖 Generated with Claude Code

https://claude.ai/code/session_019XZQMmzJbrqB9aJomKAB9z